OpenRISC 1000 (old)

Introduction

The aim of this project is to develop and maintain an OpenRISC 1000 architectural simulator. Or1ksim is a generic OpenRISC 1000 architecture simulator capable of emulating OpenRISC based computer systems.

This project was static for 2.5 years until mid-2008, but is now active again.

The latest version, 0.3.0, was released in March 2009 after 9 months of new development. This brings Or1ksim in line with the current OpenRISC 1000 architecture and adds

use standalone or as a library
support for the GDB Remote Serial Protocol
support for GDB 6.8
an OSCI TLM 2.0 SystemC interface

Or1ksim provides several unique features:

Free, open source code
High level, fast, architecture simulation that allows early code analysis and system performance evaluation
All major models of OpenCores peripheral and system controller cores supported
Easy addition of new peripheral models
Remote debugging through a network socket with the GNU Debugger (GDB)

Downloading Or1ksim

Compressed tar images of the stable and any development releases are found on the download page. You may also checkout the latest version from SVN using:

svn co http://opencores.org/ocsvn/or1k/or1k/trunk/or1ksim

(Note that the checkout process may take a while). The current top of SVN tree is not considered stable. Build it using the process described below, but remember that some patching may be needed to get a working binary.

Binaries of Or1ksim are not available. Building the stable version is straightforward.

Installation

The current stable version has been tested under Fedora 9 Linux, Centos 4.7 Linux and Cygwin 1.5.25.

First get the sources for Or1ksim 0.3.0 using the instructions above and unpack. Assuming the unpacked source is in directory or1ksim-0.3.0, and the code is to be installed in /opt/or1ksim, build and install the simulator as follows.

mkdir builddir_or1ksim
cd builddir_or1ksim
../or1ksim-0.3.0/configure --target=or32-uclinux --prefix=/opt/or1ksim
make all
make install
export PATH=/opt/or1ksim/bin:$PATH

More detailed information on installing Or1ksim (and the rest of the OpenRISC 1000 tool chain) with examples of the simulator in use may be found in the Embecosm Application Note EAN2:

The OpenCores OpenRISC 1000 Simulator and Tool Chain: Installation Guide

Documentation

Or1ksim 0.3.0 includes a new User Guide. This provides information on using and configurating Or1ksim, both as a standalone tool and as a library. It also gives some guidance on the internal structure of Or1ksim. It may be downloaded (PDF) here. The documentation can also be generated from the source to give HTML, info, DVI and PostScript.

A summary of the command options can be seen with

or32-uclinux-sim --help

For booting Linux, use the sim.cfg file in the root directory of the Linux distribution with the command

or32-uclinux-sim -f sim.cfg vmlinux

More details on Linux for OpenRISC 1000 may be found on the tool chain page.

The Embecosm Application Note EAN2 described in the Installation section above includes examples of using Or1ksim. The User Guide for the OpenRISC 1000 port of GDB 6.8 includes details of running Or1ksim with GDB.

The code is documented to take advantage of the Doxygen documentation system, which provides automatically generated, structured documentation on the files, functions and data-structures of the entire program, together with their interrelationships. This may be generated in PDF form or as HTML. The PDF version derived from the Or1ksim 0.3.0 release may be found here.

Documentation would benefit from extending, particularly with tutorial material and with more detail on the internals of the program (see Contributing, below).

Discussion Forum

Or1ksim is discussed within the OpenRISC Forum. This is now entirely web based, and can be found here.

Stable Release

The current stable release of Or1ksim is version 0.3.0. Source code, user guide and internal documentation are all available on the download page.

Key features of Or1ksim 0.3.0 are:

simulation of the integer 32-bit OpenRISC 1000 architecture (ORBIS32)
debug interface via the GDB Remote Serial Protocol
availability as a standalone program, or linkable library
simulation of various OpenCores peripherals: VGA, UART, Ethernet, GPIO, memory controller, PS2 (keyboard only) and ATA (partially).

The debug interface is compatible with GDB 6.8 for OpenRISC 1000 (see the tool chain page for further details).

For backwards compatibility, the OpenRISC JTAG interface to GDB continues to be supported. However this interface is now deprecated and will be discontinued in a future release. All new applications should use the GDB Remote Serial Protocol (RSP). If a JTAG interface is required that should be implemented via a GDB RSP server.

The following are not yet supported in Or1ksim

64-bit instructions (ORBIS64)
floating point instructions (ORFPX32/ORFPX64)
vector instructions (ORVDX64)

Note: When used as a library, only a single instance of Or1ksim may be used, due to widespread use of static and global variables in the code. Remedying this limitation is a long term objective of the project.

Since the simulator is no longer only a processor simulator, but also supports peripherals, it is now used also as the ORPsoc simulator. For example the VGA peripheral can output images like the following figure, showing uClinux booting on a VGA console:

SystemC TLM 2.0 Interface for Or1ksim

An experimental wrapper has been developed by Embecosm to provide an OSCI SystemC TLM 2.0 interface to Or1ksim. The application note describing this may be downloaded here and the software downloaded here.

Multiple Instantiations of Ork1sim

Or1ksim can be used as a library as well as a standalone program. However, because the code makes heavy use of global variables, only one instance can ever be present. This is very inconvenient for those wishing to model a multi-core system.

Stefan Wallentowitz has implemented a prototype version of Ork1sim, based on the stable Or1ksim 0.3.0 release, which fixes this problem.

A full description and the source code as a patch is currently available from www.wallentowitz.de/or1ksim.html and will shortly be made available on the OpenRISC download page.

Development Release

With the recent release of stable version 0.3.0 there is no current separate development release of Or1ksim for download.

Current development may be accessed through CVS. Work in progress includes implementation of single precision floating point instructions (JungSook Yang) and support for multiple instances (Stefan Wallentowitz).These are likely to form the basis of development release Or1ksim 0.3.1.

Other features for future development include:

providing a proper (DejaGNU) regression test suite.
adding double precision floating point support
adding support for the SR LEE bit
fixing the stall and unstall commands (1 feature, 1 bug)
letting memory blocks identify using their "name" field
providing a GDB interface to the library version of Or1ksim
spliting out the ELF loader as a standalone tool

Some features of the current Or1ksim appear incomplete or obsolete. Candidates for future removal are:

stall and unstall commands in the CLI
the custom unit compiler
dynamic execution (a build option, not completed)
support for the OpenRISC JTAG GDB interface (replaced by RSP)

Users are encouraged to suggest other features via the OpenRISC discussion forum or through the OpenRISC bug tracker.

Contributing

We are constantly looking for developers to help in the development of the simulator, though you don't need to be a highly skilled developer to do so. Many (very usefull) projects may be performed without any C programming knowledge or without an intricate knowledge of the openrisc architecture.

A few items to get you started:

Web site maintanence:

We are constantly short of manpower to maintain the website. If you feel you're up to doing some webdesign, don't hold back any longer! Some general ideas to get you started (by no means exhausive): Add a more indepth discussion of the simulator for the introduction, provide some more screen shots showing off some interesting features of the sim, or any other good idea you have in mind.
Extend the documentation:

Or1ksim now has a User Guide. However this would benefit from some good tutorial material. This is an excellent task for anyone new to or1ksim. This would involve documenting, in the form of a well narated passage (not point form!), how to get started using or1ksim, the general pitfalls that someone new to or1ksim may take and how to avoid those, some neat examples of how to use some of the more "cool" peripherals of the sim (esp. how to make use of the Ethernet peripheral), documenting the interface that is used to implement the peripherals, documenting the more arcane features of the simulator, the various execution models, branch prediction, super scaler emulation and in general what they are usefull for. If you have any questions about the above, don't hesitate to contact us on the mailing list.
Develop a proper testsuite:

The current testsuite (in directory testsuite) is "rudimentary". It is just a collection of programs giving basic exercise to each peripheral in turn. It has been known to report failure, when there is no problem and often reports success when there are serious problems.

The system would benefit from a complete rewrite, probably using DejaGNU, to properly exercise all the features of the architecture.
Test or1ksim on non-Linux platforms (various UNIX and Cygwin platforms) :

The developers do not have acess to every operating system out there. We would like the simulator to run on as many platforms as possible. If you are running on anything other than linux you would help us a great deal if you could periodically check if the simulator builds (and works) on your prefered platform, reporting any failures to the mailing list.
Add additional models of OpenCores peripherals and system controllers:

Only a small subset of the great peripherals availible at opencores are currently modeled. Some examples of peripherals to write a model for might be, wishbone rtc, IRDA communication core, usb 2.0 function core, and most things that connect to the wishbone bus. A good list may be found here.
Add a new feature

The section on the Development Release above lists several new features. Coders wishing to help are very welcome.

If you have a suggestion that you'd like to see developed, feel free to add it to the tracker or start a discussion on the openrisc mailing list.

Developers

The team currently working on or1ksim:

Jeremy Bennett, jeremybennett@opencores.org
JungSook Yang, jungsook.yang@gmail.com (floating point support)
Stefan Wallentowitz stefan.wallentowitz@tum.de (multiple instantiation)

Past Contributors

These are the people who are currently not working on the or1ksim, but have contributed in significant ways in the past:
- Erez Volk, erez@opencores.org
- Johan Rydberg, jrydberg@opencores.org
- Jimmy Chen-Min Chen, jimmy@opencores.org
- Chris Ziomkowski, chris@opencores.org
- Marko Mlinar, markom@opencores.org
- Simon Srot, simons@opencores.org
- Matjaz Breskvar, phoenix@opencores.org
- Gyorgy Jeney, nog@sdf.lonestar.org
- Damjan Lampret, damjanl@opencores.org

Page Maintainer(s)

This web page is maintained by Jeremy Bennett and Marcus Erlandsson.

Browse